/*
** Copyright (c) 2008 Mobile GCalendar
**
** Permission is hereby granted, free of charge, to any person
** obtaining a copy of this software and associated documentation
** files (the "Software"), to deal in the Software without
** restriction, including without limitation the rights to use,
** copy, modify, merge, publish, distribute, sublicense, and/or sell
** copies of the Software, and to permit persons to whom the
** Software is furnished to do so, subject to the following
** conditions:
**
** The above copyright notice and this permission notice shall be
** included in all copies or substantial portions of the Software.
**
** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
** OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
** NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
** HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
** WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
** FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
** OTHER DEALINGS IN THE SOFTWARE.
*/

/**
 *
 */
package au.edu.mq.comp.itec800.mgc.util;


/**
 * Convenience class containing static access methods for String objects
 * manipulation operations.
 *
 * @author Laurent Malvert [laurent.malvert@students.mq.edu.au]
 */
public class StringUtils
{
  /**
   * Checks if the argument at position "idx" in the variable-length
   * String list "args" actually exists.
   *
   * Returns true if the list exists and the argument is within boundaries,
   * false otherwise.
   *
   * @param idx
   *              the position to check for.
   * @param args
   *              the variable-length list of String objects to check.
   *
   * @return
   *              boolean result of the check
   */
  public static boolean       isValid(final int idx, final String ... args)
  {
    return ((args != null) && (idx >= 0) && (idx < args.length));
  }

  /**
   * A companion method to isValid(), getValidArg(args[], idx).
   *
   * Returns a safe and clean (trimmed whitespaces) String from the
   * position "idx" within the array of String objects "args".
   *
   * If the string doesn't exist or is null, returns an empty String.
   *
   * @param args
   *              the array of String objects from which to extract the
   *              valid String.
   * @param idx
   *              the desired position to look up.
   *
   * @return
   *              the valid String object, or an empty string.
   */
  public static String        getValidArg(final String[] args, final int idx)
  {
    return (isValid(idx, args) ? clean(args[idx]) : "");
  }

  /**
   * Returns a "safe/sanitized" String object from the given "src" object.
   *
   * That is, we return the same object if it's not null, and an empty
   * String otherwise.
   *
   * @param src
   *                the String object to be check for safety.
   *
   * @return
   *                the "safe" String object.
   */
  public static String        sanitize(final String src)
  {
    return ((src != null) ? src : "");
  }

  /**
   * Returns a "clean" String object from the given "src" object.
   *
   * The given String object is being check for safety with a call to
   * getSafeString(String) first, and then has its whitespaces trimmed.
   *
   * @param src
   *                the String object to be check for safety and cleanliness.
   *
   * @return
   *                the "clean" String object.
   */
  public static String        clean(final String src)
  {
    return (sanitize(src).trim());
  }
}
